<h2>DESCRIPTION</h2>

<em>r3.in.xyz</em> imports sparse XYZ data from an ASCII file into
a 3D raster map (voxels). It does this by running the <em>r.in.xyz</em>
module multiple times for different z-ranges and then assembling the
slices with <em>r.to.rast3</em>.
<p>
See the <a href="r.in.xyz.html">r.in.xyz</a> help page for general
parameter usage and tips.
<p>
The map is created using the rows, columns, and depths set by
current region settings. Be sure to check and adjust these with
the <em>g.region</em> module before performing the import.
<p>
You may either use the z-value as the data value for the voxel
(e.g. with the 'n' statistic), or alternately scan another
column for the data values to bin into the voxels. This alternate
data column can be both filtered by range and have a scaling
factor applied to it.


<h2>NOTES</h2>

The 2D and 3D horizontal region resolutions must match. See the
EXAMPLES section below.
<p>
Unlike <em>r.in.xyz</em>, reading from stdin and z-scaling are not
possible. Filtering by z-range is accomplished by setting the 3D region.
<p>
To enable parallel processing support, set the <b>workers=</b> option
to match the number of CPUs or CPU-cores available on your system.
Alternatively, the <tt>WORKERS</tt> environment variable can be set
to the number of concurrent processes desired.
<p>
Points falling exactly on a vertical bound will belong to the depth
band below them, except for points exactly on the top bound, which will
belong to the top-most slice.
<p>
The script is expected to be nearly as efficient as if it was fully
written in C.


<h2>EXAMPLE</h2>

Using the Serpent Mound dataset. (see the
 <a href="https://grasswiki.osgeo.org/wiki/LIDAR">GRASS LiDAR wiki page</a>)

<div class="code"><pre>
  #scan dataset for extent:
  r3.in.xyz -s in=Serpent_Mound_Model_LAS_Data.txt out=dummy \
     x=1 y=2 z=3 separator=space

  # set the 2D and 3D regions:
  g.region n=4323641.57 s=4320942.61 w=289020.90 e=290106.02 res=1 -a
  g.region b=166 t=216 res3=1 tbres=5 -3 -p

  r3.in.xyz in=Serpent_Mound_Model_LAS_Data.txt out=serpent3D \
     method=mean x=1 y=2 z=3 separator=space type=float
</pre></div>

The same, but aggregate and store backscatter strength from column 5
into voxels in instead of the z-value:
<div class="code"><pre>
  r3.in.xyz in=Serpent_Mound_Model_LAS_Data.txt out=serpent3D.bakscat \
     method=mean x=1 y=2 z=3 val=5 separator=space type=float
</pre></div>


<h2>KNOWN ISSUES</h2>

<em>r.to.rast3</em> always creates a <tt>double</tt> output map
regardless of input.


<h2>SEE ALSO</h2>

<em>
<a href="g.region.html">g.region</a>,
<a href="r.in.xyz.html">r.in.xyz</a>,
<a href="r.to.rast3.html">r.to.rast3</a>
</em>


<h2>AUTHOR</h2>

Hamish Bowman<br>
<i>Dunedin, New Zealand</i>

<!--
<p>
<i>Last changed: $Date$</i>
-->
